ShowTable of Contents
Introduction
This article is part of the
XPages Extensibility API Developers Guide.
This article describes how to implement incremental releases (versioning) of an XPages library. It is assumed that you have an existing XPages library containing some extensions; if not, please start with the article "
Creating an XPages Library". Suppose in the latest release of an XPages library, there are some new features that are not available in the previous release. If an application uses the new features on a server that only has the previous release of the library then the application will fail to run.
This behavior is undesirable since the required library is deployed on the server however, it is not the latest release. The solution is to use XPages library versioning.
Versioning can be applied to extensions which create and contribute XPages tag elements to the library. The supported definition elements are:
- attribute
- complex-type
- component
- composite-component
- converter
- property
- validator
There are two steps to implement versioning in XPages libraries:
- Set the tag version of the library (getTagVersion) to the latest release
- In the xsp-config file, mark the new tags with the latest release version using the since element
There is a runtime check when an XPage uses a tag marked with a release version. If the library method
getTagVersion does not return the tag's release version or later, then it is assumed that the initial version of the library is installed and the application will fail to run. However, with XPages library versioning, a more descriptive message is returned instead; explaining that a later version of the library is required.
In the first release of a library, the method
getTagVersion can return null and the initial tags do not need to be marked with a release version. However, if subsequent releases of the library contain new features then they must define their version.
Versioning
Update the library class
In the library class, implement the method
getTagVersion to return the latest release version.
package com.example.library;
import com.ibm.xsp.library.AbstractXspLibrary;
public class ExampleLibrary extends AbstractXspLibrary {
public String getTagVersion() {
return "2.0.0";
}
public String getLibraryId() {
return "com.example.library";
}
public String getPluginId() {
return "com.example.xsp";
}
public String[] getXspConfigFiles() {
return new String[] {
"META-INF/exampleExtensions.xsp-config",
};
}
public String[] getFacesConfigFiles() {
return new String[] {
"META-INF/example-faces-config.xml",
};
}
}
Once some tags are marked with a release version, the method
getTagVersion should be updated to return that version or later.
Mark the new tags
When developing later releases of your library, new features must be marked with the latest release version using the element
since in the xsp-config file. New features are marked by adding the element
since to their respective definition extension element.
<component>
<description>An example control.</description>
<display-name>Example Control</display-name>
<component-type>com.example.examplecontrol</component-type>
<component-class>com.example.component.ExampleControl</component-class>
<component-extension>
<since>2.0.0</since>
<tag-name>exampleControl</tag-name>
<component-family>com.example.examplecontrol</component-family>
<renderer-type>com.example.examplecontrol</renderer-type>
</component-extension>
</component>
These are the respective extension elements for the supported definitions.
- attribute-extension
- complex-extension
- component-extension
- composite-extension
- converter-extension
- property-extension
- validator-extension
When adding a new tag, the
since element should only be added to the tag itself, not to all the new properties within the tag. However, when adding a new property to an existing tag, the
since element should only be added to the new property.
For further information, you may read the article "
XPagesPageVersions.htm
" which explains how page versioning works in the XPages runtime. Library Tag Versioning uses a similar mechanism.